home *** CD-ROM | disk | FTP | other *** search
/ Programmer Plus 2007 / Programmer-Plus-2007.iso / Programming / Compilers / digital marsC compier / dm / include / gc_cpp.h < prev    next >
Encoding:
C/C++ Source or Header  |  2001-06-14  |  11.5 KB  |  350 lines
  1. #ifndef GC_CPP_H
  2. #define GC_CPP_H
  3. /****************************************************************************
  4. Copyright (c) 1994 by Xerox Corporation.  All rights reserved.
  5.  
  6. THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED
  7. OR IMPLIED.  ANY USE IS AT YOUR OWN RISK.
  8.  
  9. Permission is hereby granted to use or copy this program for any
  10. purpose, provided the above notices are retained on all copies.
  11. Permission to modify the code and to distribute modified code is
  12. granted, provided the above notices are retained, and a notice that
  13. the code was modified is included with the above copyright notice.
  14. ****************************************************************************
  15.  
  16. C++ Interface to the Boehm Collector
  17.  
  18.     John R. Ellis and Jesse Hull 
  19.  
  20. This interface provides access to the Boehm collector.  It provides
  21. basic facilities similar to those described in "Safe, Efficient
  22. Garbage Collection for C++", by John R. Elis and David L. Detlefs
  23. (ftp://ftp.parc.xerox.com/pub/ellis/gc).
  24.  
  25. All heap-allocated objects are either "collectable" or
  26. "uncollectable".  Programs must explicitly delete uncollectable
  27. objects, whereas the garbage collector will automatically delete
  28. collectable objects when it discovers them to be inaccessible.
  29. Collectable objects may freely point at uncollectable objects and vice
  30. versa.
  31.  
  32. Objects allocated with the built-in "::operator new" are uncollectable.
  33.  
  34. Objects derived from class "gc" are collectable.  For example:
  35.  
  36.     class A: public gc {...};
  37.     A* a = new A;       // a is collectable. 
  38.  
  39. Collectable instances of non-class types can be allocated using the GC
  40. (or UseGC) placement:
  41.  
  42.     typedef int A[ 10 ];
  43.     A* a = new (GC) A;
  44.  
  45. Uncollectable instances of classes derived from "gc" can be allocated
  46. using the NoGC placement:
  47.  
  48.     class A: public gc {...};
  49.     A* a = new (NoGC) A;   // a is uncollectable.
  50.  
  51. Both uncollectable and collectable objects can be explicitly deleted
  52. with "delete", which invokes an object's destructors and frees its
  53. storage immediately.
  54.  
  55. A collectable object may have a clean-up function, which will be
  56. invoked when the collector discovers the object to be inaccessible.
  57. An object derived from "gc_cleanup" or containing a member derived
  58. from "gc_cleanup" has a default clean-up function that invokes the
  59. object's destructors.  Explicit clean-up functions may be specified as
  60. an additional placement argument:
  61.  
  62.     A* a = ::new (GC, MyCleanup) A;
  63.  
  64. An object is considered "accessible" by the collector if it can be
  65. reached by a path of pointers from static variables, automatic
  66. variables of active functions, or from some object with clean-up
  67. enabled; pointers from an object to itself are ignored.
  68.  
  69. Thus, if objects A and B both have clean-up functions, and A points at
  70. B, B is considered accessible.  After A's clean-up is invoked and its
  71. storage released, B will then become inaccessible and will have its
  72. clean-up invoked.  If A points at B and B points to A, forming a
  73. cycle, then that's considered a storage leak, and neither will be
  74. collectable.  See the interface gc.h for low-level facilities for
  75. handling such cycles of objects with clean-up.
  76.  
  77. The collector cannot guarrantee that it will find all inaccessible
  78. objects.  In practice, it finds almost all of them.
  79.  
  80.  
  81. Cautions:
  82.  
  83. 1. Be sure the collector has been augmented with "make c++".
  84.  
  85. 2.  If your compiler supports the new "operator new[]" syntax, then
  86. add -DOPERATOR_NEW_ARRAY to the Makefile.
  87.  
  88. If your compiler doesn't support "operator new[]", beware that an
  89. array of type T, where T is derived from "gc", may or may not be
  90. allocated as a collectable object (it depends on the compiler).  Use
  91. the explicit GC placement to make the array collectable.  For example:
  92.  
  93.     class A: public gc {...};
  94.     A* a1 = new A[ 10 ];        // collectable or uncollectable?
  95.     A* a2 = new (GC) A[ 10 ];   // collectable
  96.  
  97. 3. The destructors of collectable arrays of objects derived from
  98. "gc_cleanup" will not be invoked properly.  For example:
  99.  
  100.     class A: public gc_cleanup {...};
  101.     A* a = new (GC) A[ 10 ];    // destructors not invoked correctly
  102.  
  103. Typically, only the destructor for the first element of the array will
  104. be invoked when the array is garbage-collected.  To get all the
  105. destructors of any array executed, you must supply an explicit
  106. clean-up function:
  107.  
  108.     A* a = new (GC, MyCleanUp) A[ 10 ];
  109.  
  110. (Implementing clean-up of arrays correctly, portably, and in a way
  111. that preserves the correct exception semantics requires a language
  112. extension, e.g. the "gc" keyword.)
  113.  
  114. 4. Compiler bugs:
  115.  
  116. * Solaris 2's CC (SC3.0) doesn't implement t->~T() correctly, so the
  117. destructors of classes derived from gc_cleanup won't be invoked.
  118. You'll have to explicitly register a clean-up function with
  119. new-placement syntax.
  120.  
  121. * Evidently cfront 3.0 does not allow destructors to be explicitly
  122. invoked using the ANSI-conforming syntax t->~T().  If you're using
  123. cfront 3.0, you'll have to comment out the class gc_cleanup, which
  124. uses explicit invocation.
  125.  
  126. 5. GC name conflicts:
  127.  
  128. Many other systems seem to use the identifier "GC" as an abbreviation
  129. for "Graphics Context".  Since version 5.0, GC placement has been replaced
  130. by UseGC.  GC is an alias for UseGC, unless GC_NAME_CONFLICT is defined.
  131.  
  132. ****************************************************************************/
  133.  
  134. #include "gc.h"
  135.  
  136. #ifndef THINK_CPLUS
  137. #define _cdecl
  138. #endif
  139.  
  140. #if ! defined( OPERATOR_NEW_ARRAY ) \
  141.     && (__BORLANDC__ >= 0x450 || (__GNUC__ >= 2 && __GNUC_MINOR__ >= 6) \
  142.     || __WATCOMC__ >= 1050 || _MSC_VER >= 1100 || _ENABLE_ARRAYNEW)
  143. #   define OPERATOR_NEW_ARRAY
  144. #endif
  145.  
  146. enum GCPlacement {UseGC,
  147. #ifndef GC_NAME_CONFLICT
  148.           GC=UseGC,
  149. #endif
  150.                   NoGC, PointerFreeGC};
  151.  
  152. class gc {public:
  153.     inline void* operator new( size_t size );
  154.     inline void* operator new( size_t size, GCPlacement gcp );
  155.     inline void operator delete( void* obj );
  156.  
  157. #ifdef OPERATOR_NEW_ARRAY
  158.     inline void* operator new[]( size_t size );
  159.     inline void* operator new[]( size_t size, GCPlacement gcp );
  160.     inline void operator delete[]( void* obj );
  161. #endif /* OPERATOR_NEW_ARRAY */
  162.     };    
  163.     /*
  164.     Instances of classes derived from "gc" will be allocated in the 
  165.     collected heap by default, unless an explicit NoGC placement is
  166.     specified. */
  167.  
  168. class gc_cleanup: virtual public gc {public:
  169.     inline gc_cleanup();
  170.     inline virtual ~gc_cleanup();
  171. private:
  172.     inline static void _cdecl cleanup( void* obj, void* clientData );};
  173.     /*
  174.     Instances of classes derived from "gc_cleanup" will be allocated
  175.     in the collected heap by default.  When the collector discovers an
  176.     inaccessible object derived from "gc_cleanup" or containing a
  177.     member derived from "gc_cleanup", its destructors will be
  178.     invoked. */
  179.  
  180. extern "C" {typedef void (*GCCleanUpFunc)( void* obj, void* clientData );}
  181.  
  182. #ifdef _MSC_VER
  183.   // Disable warning that "no matching operator delete found; memory will
  184.   // not be freed if initialization throws an exception"
  185. # pragma warning(disable:4291)
  186. #endif
  187.  
  188. inline void* operator new( 
  189.     size_t size, 
  190.     GCPlacement gcp,
  191.     GCCleanUpFunc cleanup = 0,
  192.     void* clientData = 0 );
  193.     /*
  194.     Allocates a collectable or uncollected object, according to the
  195.     value of "gcp".
  196.  
  197.     For collectable objects, if "cleanup" is non-null, then when the
  198.     allocated object "obj" becomes inaccessible, the collector will
  199.     invoke the function "cleanup( obj, clientData )" but will not
  200.     invoke the object's destructors.  It is an error to explicitly
  201.     delete an object allocated with a non-null "cleanup".
  202.  
  203.     It is an error to specify a non-null "cleanup" with NoGC or for
  204.     classes derived from "gc_cleanup" or containing members derived
  205.     from "gc_cleanup". */
  206.  
  207. #ifdef OPERATOR_NEW_ARRAY
  208.  
  209. #ifdef _MSC_VER
  210.  /** This ensures that the system default operator new[] doesn't get
  211.   *  undefined, which is what seems to happen on VC++ 6 for some reason
  212.   *  if we define a multi-argument operator new[].
  213.   *  There seems to be really redirect new in this environment without
  214.   *  including this everywhere. 
  215.   */
  216.  inline void *operator new[]( size_t size )
  217.  {
  218.     return GC_MALLOC_UNCOLLECTABLE( size );
  219.  }
  220.  
  221.  inline void operator delete[](void* obj)
  222.  {
  223.     GC_FREE(obj);
  224.  };
  225.  
  226.  inline void* operator new( size_t size)
  227.  {
  228.     return GC_MALLOC_UNCOLLECTABLE( size);
  229.  };   
  230.  
  231.  inline void operator delete(void* obj)
  232.  {
  233.     GC_FREE(obj);
  234.  };
  235.  
  236.  
  237. // This new operator is used by VC++ in case of Debug builds !
  238.   inline void* operator new( size_t size,
  239.               int ,//nBlockUse,
  240.               const char * szFileName,
  241.               int nLine
  242.               ) {
  243. # ifndef GC_DEBUG
  244.      return GC_malloc_uncollectable( size );
  245. # else
  246.      return GC_debug_malloc_uncollectable(size, szFileName, nLine);
  247. # endif
  248.   }
  249.  
  250. #endif /* _MSC_VER */
  251.  
  252. inline void* operator new[](
  253.     size_t size, 
  254.     GCPlacement gcp,
  255.     GCCleanUpFunc cleanup = 0,
  256.     void* clientData = 0 );
  257.     /*
  258.     The operator new for arrays, identical to the above. */
  259.  
  260. #endif /* OPERATOR_NEW_ARRAY */
  261.  
  262. /****************************************************************************
  263.  
  264. Inline implementation
  265.  
  266. ****************************************************************************/
  267.  
  268. inline void* gc::operator new( size_t size ) {
  269.     return GC_MALLOC( size );}
  270.     
  271. inline void* gc::operator new( size_t size, GCPlacement gcp ) {
  272.     if (gcp == UseGC) 
  273.         return GC_MALLOC( size );
  274.     else if (gcp == PointerFreeGC)
  275.     return GC_MALLOC_ATOMIC( size );
  276.     else
  277.         return GC_MALLOC_UNCOLLECTABLE( size );}
  278.  
  279. inline void gc::operator delete( void* obj ) {
  280.     GC_FREE( obj );}
  281.     
  282.  
  283. #ifdef OPERATOR_NEW_ARRAY
  284.  
  285. inline void* gc::operator new[]( size_t size ) {
  286.     return gc::operator new( size );}
  287.     
  288. inline void* gc::operator new[]( size_t size, GCPlacement gcp ) {
  289.     return gc::operator new( size, gcp );}
  290.  
  291. inline void gc::operator delete[]( void* obj ) {
  292.     gc::operator delete( obj );}
  293.     
  294. #endif /* OPERATOR_NEW_ARRAY */
  295.  
  296.  
  297. inline gc_cleanup::~gc_cleanup() {
  298.     GC_REGISTER_FINALIZER_IGNORE_SELF( GC_base(this), 0, 0, 0, 0 );}
  299.  
  300. inline void gc_cleanup::cleanup( void* obj, void* displ ) {
  301.     ((gc_cleanup*) ((char*) obj + (ptrdiff_t) displ))->~gc_cleanup();}
  302.  
  303. inline gc_cleanup::gc_cleanup() {
  304.     GC_finalization_proc oldProc;
  305.     void* oldData;
  306.     void* base = GC_base( (void *) this );
  307.     if (0 != base)  {
  308.       // Don't call the debug version, since this is a real base address.
  309.       GC_register_finalizer_ignore_self( 
  310.         base, (GC_finalization_proc)cleanup, (void*) ((char*) this - (char*) base), 
  311.         &oldProc, &oldData );
  312.       if (0 != oldProc) {
  313.         GC_register_finalizer_ignore_self( base, oldProc, oldData, 0, 0 );}}}
  314.  
  315. inline void* operator new( 
  316.     size_t size, 
  317.     GCPlacement gcp,
  318.     GCCleanUpFunc cleanup,
  319.     void* clientData )
  320. {
  321.     void* obj;
  322.  
  323.     if (gcp == UseGC) {
  324.         obj = GC_MALLOC( size );
  325.         if (cleanup != 0) 
  326.             GC_REGISTER_FINALIZER_IGNORE_SELF( 
  327.                 obj, cleanup, clientData, 0, 0 );}
  328.     else if (gcp == PointerFreeGC) {
  329.         obj = GC_MALLOC_ATOMIC( size );}
  330.     else {
  331.         obj = GC_MALLOC_UNCOLLECTABLE( size );};
  332.     return obj;}
  333.         
  334.  
  335. #ifdef OPERATOR_NEW_ARRAY
  336.  
  337. inline void* operator new[]( 
  338.     size_t size, 
  339.     GCPlacement gcp,
  340.     GCCleanUpFunc cleanup,
  341.     void* clientData )
  342. {
  343.     return ::operator new( size, gcp, cleanup, clientData );}
  344.  
  345. #endif /* OPERATOR_NEW_ARRAY */
  346.  
  347.  
  348. #endif /* GC_CPP_H */
  349.  
  350.